home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 98 / Skunkware 98.iso / src / interp / perl5.005.tar.gz / perl5.005.tar / perl5.005 / vms / ext / Stdio / Stdio.pm < prev    next >
Text File  |  1998-04-02  |  9KB  |  256 lines
  1. #   VMS::Stdio - VMS extensions to Perl's stdio calls
  2. #
  3. #   Author:  Charles Bailey  bailey@genetics.upenn.edu
  4. #   Version: 2.1
  5. #   Revised: 24-Mar-1998
  6.  
  7. package VMS::Stdio;
  8.  
  9. require 5.002;
  10. use vars qw( $VERSION @EXPORT @EXPORT_OK %EXPORT_TAGS @ISA );
  11. use Carp '&croak';
  12. use DynaLoader ();
  13. use Exporter ();
  14.  
  15. $VERSION = '2.1';
  16. @ISA = qw( Exporter DynaLoader IO::File );
  17. @EXPORT = qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY &O_NOWAIT
  18.               &O_RDONLY &O_RDWR  &O_TRUNC &O_WRONLY );
  19. @EXPORT_OK = qw( &flush &getname &remove &rewind &sync &setdef &tmpnam
  20.                  &vmsopen &vmssysopen &waitfh &writeof );
  21. %EXPORT_TAGS = ( CONSTANTS => [ qw( &O_APPEND &O_CREAT &O_EXCL  &O_NDELAY
  22.                                     &O_NOWAIT &O_RDONLY &O_RDWR &O_TRUNC
  23.                                     &O_WRONLY ) ],
  24.                  FUNCTIONS => [ qw( &flush &getname &remove &rewind &setdef
  25.                                     &sync &tmpnam &vmsopen &vmssysopen
  26.                                     &waitfh &writeof ) ] );
  27.  
  28. bootstrap VMS::Stdio $VERSION;
  29.  
  30. sub AUTOLOAD {
  31.     my($constname) = $AUTOLOAD;
  32.     $constname =~ s/.*:://;
  33.     if ($constname =~ /^O_/) {
  34.       my($val) = constant($constname);
  35.       defined $val or croak("Unknown VMS::Stdio constant $constname");
  36.       *$AUTOLOAD = sub { $val; }
  37.     }
  38.     else { # We don't know about it; hand off to IO::File
  39.       require IO::File;
  40.  
  41.       *$AUTOLOAD = eval "sub { shift->IO::File::$constname(\@_) }";
  42.       croak "Error autoloading IO::File::$constname: $@" if $@;
  43.     }
  44.     goto &$AUTOLOAD;
  45. }
  46.  
  47. sub DESTROY { close($_[0]); }
  48.  
  49.  
  50. ################################################################################
  51. # Intercept calls to old VMS::stdio package, complain, and hand off
  52. # This will be removed in a future version of VMS::Stdio
  53.  
  54. package VMS::stdio;
  55.  
  56. sub AUTOLOAD {
  57.   my($func) = $AUTOLOAD;
  58.   $func =~ s/.*:://;
  59.   # Cheap trick: we know DynaLoader has required Carp.pm
  60.   Carp::carp("Old package VMS::stdio is now VMS::Stdio; please update your code");
  61.   if ($func eq 'vmsfopen') {
  62.     Carp::carp("Old function &vmsfopen is now &vmsopen");
  63.     goto &VMS::Stdio::vmsopen;
  64.   }
  65.   elsif ($func eq 'fgetname') {
  66.     Carp::carp("Old function &fgetname is now &getname");
  67.     goto &VMS::Stdio::getname;
  68.   }
  69.   else { goto &{"VMS::Stdio::$func"}; }
  70. }
  71.  
  72. package VMS::Stdio;  # in case we ever use AutoLoader
  73.  
  74. 1;
  75.  
  76. __END__
  77.  
  78. =head1 NAME
  79.  
  80. VMS::Stdio - standard I/O functions via VMS extensions
  81.  
  82. =head1 SYNOPSIS
  83.  
  84. use VMS::Stdio qw( &flush &getname &remove &rewind &setdef &sync &tmpnam
  85.                    &vmsopen &vmssysopen &waitfh &writeof );
  86. setdef("new:[default.dir]");
  87. $uniquename = tmpnam;
  88. $fh = vmsopen("my.file","rfm=var","alq=100",...) or die $!;
  89. $name = getname($fh);
  90. print $fh "Hello, world!\n";
  91. flush($fh);
  92. sync($fh);
  93. rewind($fh);
  94. $line = <$fh>;
  95. undef $fh;  # closes file
  96. $fh = vmssysopen("another.file", O_RDONLY | O_NDELAY, 0, "ctx=bin");
  97. sysread($fh,$data,128);
  98. waitfh($fh);
  99. close($fh);
  100. remove("another.file");
  101. writeof($pipefh);
  102. =head1 DESCRIPTION
  103.  
  104. This package gives Perl scripts access via VMS extensions to several
  105. C stdio operations not available through Perl's CORE I/O functions.
  106. The specific routines are described below.  These functions are
  107. prototyped as unary operators, with the exception of C<vmsopen>
  108. and C<vmssysopen>, which can take any number of arguments, and
  109. C<tmpnam>, which takes none.
  110.  
  111. All of the routines are available for export, though none are
  112. exported by default.  All of the constants used by C<vmssysopen>
  113. to specify access modes are exported by default.  The routines
  114. are associated with the Exporter tag FUNCTIONS, and the constants
  115. are associated with the Exporter tag CONSTANTS, so you can more
  116. easily choose what you'd like to import:
  117.  
  118.     # import constants, but not functions
  119.     use VMS::Stdio;  # same as use VMS::Stdio qw( :DEFAULT );
  120.     # import functions, but not constants
  121.     use VMS::Stdio qw( !:CONSTANTS :FUNCTIONS ); 
  122.     # import both
  123.     use VMS::Stdio qw( :CONSTANTS :FUNCTIONS ); 
  124.     # import neither
  125.     use VMS::Stdio ();
  126.  
  127. Of course, you can also choose to import specific functions by
  128. name, as usual.
  129.  
  130. This package C<ISA> IO::File, so that you can call IO::File
  131. methods on the handles returned by C<vmsopen> and C<vmssysopen>.
  132. The IO::File package is not initialized, however, until you
  133. actually call a method that VMS::Stdio doesn't provide.  This
  134. is doen to save startup time for users who don't wish to use
  135. the IO::File methods.
  136.  
  137. B<Note:>  In order to conform to naming conventions for Perl
  138. extensions and functions, the name of this package has been
  139. changed to VMS::Stdio as of Perl 5.002, and the names of some
  140. routines have been changed.  Calls to the old VMS::stdio routines
  141. will generate a warning, and will be routed to the equivalent
  142. VMS::Stdio function.  This compatibility interface will be
  143. removed in a future release of this extension, so please
  144. update your code to use the new routines.
  145.  
  146. =over
  147.  
  148. =item flush
  149.  
  150. This function causes the contents of stdio buffers for the specified
  151. file handle to be flushed.  If C<undef> is used as the argument to
  152. C<flush>, all currently open file handles are flushed.  Like the CRTL
  153. fflush() routine, it does not flush any underlying RMS buffers for the
  154. file, so the data may not be flushed all the way to the disk.  C<flush>
  155. returns a true value if successful, and C<undef> if not.
  156.  
  157. =item getname
  158.  
  159. The C<getname> function returns the file specification associated
  160. with a Perl I/O handle.  If an error occurs, it returns C<undef>.
  161.  
  162. =item remove
  163.  
  164. This function deletes the file named in its argument, returning
  165. a true value if successful and C<undef> if not.  It differs from
  166. the CORE Perl function C<unlink> in that it does not try to
  167. reset file protection if the original protection does not give
  168. you delete access to the file (cf. L<perlvms>).  In other words,
  169. C<remove> is equivalent to
  170.  
  171.   unlink($file) if VMS::Filespec::candelete($file);
  172.  
  173. =item rewind
  174.  
  175. C<rewind> resets the current position of the specified file handle
  176. to the beginning of the file.  It's really just a convenience
  177. method equivalent in effect to C<seek($fh,0,0)>.  It returns a
  178. true value if successful, and C<undef> if it fails.
  179.  
  180. =item setdef
  181.  
  182. This function sets the default device and directory for the process.
  183. It is identical to the built-in chdir() operator, except that the change
  184. persists after Perl exits.  It returns a true value on success, and
  185. C<undef> if it encounters and error.
  186.  
  187. =item sync
  188.  
  189. This function flushes buffered data for the specified file handle
  190. from stdio and RMS buffers all the way to disk.  If successful, it
  191. returns a true value; otherwise, it returns C<undef>.
  192.  
  193. =item tmpnam
  194.  
  195. The C<tmpnam> function returns a unique string which can be used
  196. as a filename when creating temporary files.  If, for some
  197. reason, it is unable to generate a name, it returns C<undef>.
  198.  
  199. =item vmsopen
  200.  
  201. The C<vmsopen> function enables you to specify optional RMS arguments
  202. to the VMS CRTL when opening a file.  Its operation is similar to the built-in
  203. Perl C<open> function (see L<perlfunc> for a complete description),
  204. but it will only open normal files; it cannot open pipes or duplicate
  205. existing I/O handles.  Up to 8 optional arguments may follow the
  206. file name.  These arguments should be strings which specify
  207. optional file characteristics as allowed by the CRTL. (See the
  208. CRTL reference manual description of creat() and fopen() for details.)
  209. If successful, C<vmsopen> returns a VMS::Stdio file handle; if an
  210. error occurs, it returns C<undef>.
  211.  
  212. You can use the file handle returned by C<vmsopen> just as you
  213. would any other Perl file handle.  The class VMS::Stdio ISA
  214. IO::File, so you can call IO::File methods using the handle
  215. returned by C<vmsopen>.  However, C<use>ing VMS::Stdio does not
  216. automatically C<use> IO::File; you must do so explicitly in
  217. your program if you want to call IO::File methods.  This is
  218. done to avoid the overhead of initializing the IO::File package
  219. in programs which intend to use the handle returned by C<vmsopen>
  220. as a normal Perl file handle only.  When the scalar containing
  221. a VMS::Stdio file handle is overwritten, C<undef>d, or goes
  222. out of scope, the associated file is closed automatically.
  223.  
  224. =item vmssysopen
  225.  
  226. This function bears the same relationship to the CORE function
  227. C<sysopen> as C<vmsopen> does to C<open>.  Its first three arguments
  228. are the name, access flags, and permissions for the file.  Like
  229. C<vmsopen>, it takes up to 8 additional string arguments which
  230. specify file characteristics.  Its return value is identical to
  231. that of C<vmsopen>.
  232.  
  233. The symbolic constants for the mode argument are exported by
  234. VMS::Stdio by default, and are also exported by the Fcntl package.
  235.  
  236. =item waitfh
  237.  
  238. This function causes Perl to wait for the completion of an I/O
  239. operation on the file handle specified as its argument.  It is
  240. used with handles opened for asynchronous I/O, and performs its
  241. task by calling the CRTL routine fwait().
  242.  
  243. =item writeof
  244.  
  245. This function writes an EOF to a file handle, if the device driver
  246. supports this operation.  Its primary use is to send an EOF to a
  247. subprocess through a pipe opened for writing without closing the
  248. pipe.  It returns a true value if successful, and C<undef> if
  249. it encounters an error.
  250.  
  251. =head1 REVISION
  252.  
  253. This document was last revised on 10-Dec-1996, for Perl 5.004.
  254.  
  255. =cut
  256.